.TH stoker 8 "14 November 2008" "version 0.91" "Stoker Manual"
.SH NAME
stoker \- an LDAP-aware utility for administering distributed systems
.SH SYNOPSIS
.B stoker
[OPTIONS] [<machine(s)> <command> [options] [arguments]]

.B stoker
<\-a | \-\-all> [OPTIONS] [<command> [options] [arguments]]
.SH DESCRIPTION
Stoker is an LDAP-aware tool for remote system administration.
It is designed as a centralized management tool for cluster computing systems.
Stoker can execute commands on remote machines, copy files between hosts,
ping remote hosts to check status, and wake remote hosts from S3 or S4 ACPI
sleep states by means of Wake-On-LAN.
Stoker is also easily extensible through shell scripts or Python code.
.PP
To effect remote operations, Stoker uses ssh(1) as a transport.
SSH needs to be configured so that Stoker users can log in to trusted
machines using key-based authentication (i.e. password-less login).
It should be noted that Stoker will NOT work with ssh(1) password-based
authentication, as Stoker has been designed exclusively as a batch-mode tool.
.PP
Stoker operates on "targets", or lists of machines and groups defined by
"sources".
A source is simply a collection of machines (and perhaps groups
made from those machines) in a format accessible to Stoker.
Currently, two
sources are available: the LDAP source and the local source (see below).
Stoker CANNOT combine sources for target resolution (i.e. groups of LDAP
machines must be defined by LDAP and cannot contain local machines or groups,
and vice-versa).
.SH OPTIONS
.TP
.B \-a \-\-all
Operate on all machines in all selected sources.
If this option is given, then Stoker uses the second syntactical form given
in the Synopsis, and the list of machines and groups upon which to operate
is omitted from the command line.
.TP
.B \-c \-\-concatenate
Concatenate standard output and standard error from all child processes,
instead of separating results by target. No separator lines will be printed.
.TP
.B \-e <path> \-\-error-to=<path>
Write child process standard error to <path>, in addition to the screen. If
<path> is a file, then <path> will be replaced by the concatenated standard
error of all child processes, without separators. If <path> is a directory,
then the standard error of each child process will be written on a per-target
basis to a file with the same name as the target, located in the <path>
directory.
.TP
.B \-g \-\-list\-groups
List defined Stoker groups from all selected sources.
Sources can be limited by means of the \-s option.
.TP
.B \-h \-\-help
Show basic usage information
.TP
.B \-i <path> \-\-input-from=<path>
Read standard input for each sub-process from <path>. If <path> is a file,
then all sub-processes will receive the same standard input data from that
file. If <path> is a directory, then for each target, try to read a file
from <path> that has the same hostname as the target. If a file does not
exist for a particular target, then use an empty string as standard input
for that target. This option can be specified multiple times on the
command line, and the different <path> arguments will be tried in order, from
left to right, until one of them matches and standard input is read. If all
paths are directories, and no match is found for a target, an empty string
will be used as standard input for that target.
.TP
.B \-l \-\-list\-commands
List recognized Stoker commands
.TP
.B \-m \-\-list\-machines
List all available machines from all selected sources.
Sources can be limited by means of the \-s option.
.TP
.B \-o <path> \-\-output-to=<path>
Write child process standard output to <path>, in addition to the screen. If
<path> is a file, then <path> will be replaced by the concatenated standard
output of all child processes, without separators. If <path> is a directory,
then the standard output of each child process will be written on a per-target
basis to a file with the same name as the target, located in the <path>
directory.
.TP
.B \-p \-\-parallel
Execute commands in parallel, using as many threads as specified in the
configuration file (default 16) or -t option.
Without this switch, Stoker operates sequentially, operating on one remote
machine at a time.
.TP
.B \-q \-\-no\-details
Suppress printing the command standard output and standard error information
at the end of execution
.TP
.B \-Q \-\-no\-summary
Do not print success/failure messages as commands complete
.TP
.B \-r <command> \-\-reference=<command>
Show a terse synopsis of the syntax of a Stoker command
.TP
.B \-s <sourcelist> \-\-sources=<sourcelist>
Limit machine sources to the sources specified in <sourcelist>, which must
be a comma-separated list of sources.
Machines specified as targets to Stoker will be resolved in the order of the
sources given with this option.
If this option is omitted, Stoker uses all configured sources and resolves
targets in an arbitrary order.
.TP
.B \-S \-\-list\-sources
List available machine and group sources
.TP
.B \-t <threadcount> \-\-threads=<threadcount>
Execute in parallel, and limit the number of concurrent threads to
<threadcount> (implies \-p).
The maximum <threadcount> that can be specified
depends upon the capabilities of the system on which Stoker is running.
.TP
.B \-v \-\-version
Show Stoker version information
.SH FILES
Stoker requires a configuration file to define machine sources and basic
setup parameters.
Stoker first looks for a file named "stoker.conf" in the current working
directory.
If this file does not exist, Stoker looks for configuration in the path
"$HOME/.stoker/stoker.conf".
Finally, Stoker looks for "/etc/stoker.conf" if a per-user configuration
file is not available.
See stoker.conf(5) for configuration details.
.SH EXAMPLES
.TP
Execute /bin/hostname on machines host1 and host2:
stoker host1,host2 exec /bin/hostname
.PP
.TP
Copy /root/foo.txt to /root on all machines in the "foobar" group:
stoker foobar copy /root/foo.txt /root
.PP
.TP
Execute /bin/hostname on all machines known to Stoker:
stoker -a exec /bin/hostname
.PP
.TP
An advanced example:
stoker \-i a/ \-i b \-o out/ \-e err/ foobar exec -s myscript \-i
.PP
In the advanced example, execute a script named \fBmyscript\fR, passing the
\-i option to \fBmyscript\fR and passing standard input as follows: if a
file with the same name as a target in foobar is found in the a/ directory,
use the contents of that file as standard input for that target; otherwise,
use the contents of file b as the default standard input. Write per-target
standard output files to the out/ directory and per-target standard error
files to the err/ directory.
.SH EXIT STATUS
Stoker returns a zero exit status if all commands it executes are completed
successfully.
Otherwise, a non-zero exit code will be returned.
The exact return code depends upon the return code of the malfunctioning
sub-process.
.SH MACHINES AND GROUPS
Stoker obtains machine and group information from either a local source
(machine file) or an LDAP server. Beginning with Stoker 0.91, it is also
possible to use a MySQL server as a machine source.
See stoker_local(5) and stoker_ldap(5) for details.
.SH SECURITY CONSIDERATIONS
Since Stoker requires that ssh(1) be configured to permit password-less
logins for Stoker users, there are potential security concerns that may
arise if the user account is compromised (since all machines will be
reachable via password-less SSH).
.SH SEE ALSO
stoker.conf(5), scf2(5), stoker_exec(8), stoker_copy(8), stoker_wake(8),
stoker_ping(8), stoker_do(8), stoker_py(8), ssh(1), stoker_ldap(5),
stoker_local(5), stoker_mysql(5)
.SH AUTHOR
Mike Murphy (mamurph@cs.clemson.edu)
.SH DISCLAIMER
This material is based upon work supported under a National Science
Foundation Graduate Research Fellowship.
Any opinions, findings, conclusions or recommendations expressed in this
publication are those of the author(s) and do not necessarily reflect the
views of the National Science Foundation.
